<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Real-Time Audio</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="Using.html" title="Using Csound" />
    <link rel="prev" href="UsingDesign.html" title="How Csound works" />
    <link rel="next" href="RealTimeWindows.html" title="Windows" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Real-Time Audio</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="UsingDesign.html">Prev</a> </td>
          <th width="60%" align="center">Using Csound</th>
          <td width="20%" align="right"> <a accesskey="n" href="RealTimeWindows.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="section">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="UsingRealTime"></a>Real-Time Audio</h2>
          </div>
        </div>
      </div>
      <p>
      The following information applies mostly to csound being run directly from the command line. Front-ends implement these features in different ways, but knowledge of them is necessary in some of them.
    </p>
      <p>
      The <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerI"><em class="citetitle">-i</em></a> and <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerO"><em class="citetitle">-o</em></a> flags can are used to specify realtime output instead of the ordinary non-realtime file output. You should use <code class="literal">-o dac</code> for realtime output and <code class="literal">-i adc</code> for realtime input. Naturally, you can use either one or both if your hardware supports it. You can also specify the hardware you want to use by appending a device number or name to the flag (See <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerI"><em class="citetitle">-i</em></a> and <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerO"><em class="citetitle">-o</em></a>).
    </p>
      <p>
      You might also need to use the <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusPlusRtaudio"><em class="citetitle">-+rtaudio</em></a> flag to specify the driver interface to be used. Csound defaults to using Portaudio, which is cross-plaform and reliable, but for better performance, you might need to use ALSA or JACK on linux, and CoreAudio on Mac. You can use ASIO on Windows if your version of Portaudio has been compiled with ASIO support.
    </p>
      <p>
      You can see a list of available devices by giving a device number which is out of range, for instance <code class="literal">-o dac99</code>. This will also reveal if you have ASIO available if you are using PortAudio.
    </p>
      <h3><a id="idp76960720"></a>
      Period &amp; Buffer Sizes</h3>
      <p>Period and buffer sizes will vary greatly from one machine to
      another. Lower buffer sizes will result in lower latency, but might 
      cause breakups or clicks in the audio. The Csound
      flags which control period and buffer sizes are <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerB"><em class="citetitle">-b</em></a> and <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperB"><em class="citetitle">-B</em></a>,
      respectively. Buffer size is hardware dependant, and some
      experimentation may be necessary to find the optimal balance between
      low latency performance and uninterrupted audio output. The values
      given to <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerB"><em class="citetitle">-b</em></a> and <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperB"><em class="citetitle">-B</em></a> should be powers of two, and the value of <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperB"><em class="citetitle">-B</em></a>
      should be at least one power of two higher than that of <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerB"><em class="citetitle">-b</em></a>.
    </p>
      <p>Currently, with <code class="literal"><a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperB"><em class="citetitle">-B</em></a></code> set to 512, audio output latency
      is about 12 milliseconds, fast enough for reasonably responsive
      keyboad playing. Even shorter latencies, are feasible on some systems.</p>
      <h3><a id="idp76969536"></a>Control Rate</h3>
      <p>
      Low values for ksmps will in general give a higher quality of
      synthesis, but will consume more system resources. There is no hard
      and fast rule for setting ksmps - different orchestras will require
      different control rates. A waveguide instrument will need a ksmps of
      1 (and may not be suitable for realtime use), whereas a simple FM
      synth may be run with a higher ksmps without noticeable degradation of
      sound. If the FM synth were to be used to play a monophonic bassline,
      a very low ksmps may be used, however more complex note clusters will
      require a higher ksmps. A well-tuned Linux system should be capable of
      running even complex polyphonic synths with ksmps values as low as 4
      or 8. If full duplex audio is required, <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusLowerB"><em class="citetitle">-b</em></a> must be an integer
      multiple of ksmps. Bearing this in mind, a rule of thumb might be to
      only use powers of two for ksmps.
    </p>
      <p>
      Some settings differ according to platform. See further below for information for each platform.
    </p>
      <div class="section">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="RealTimeLinux"></a>Realtime I/O on Linux</h3>
            </div>
          </div>
        </div>
        <p>
    Under Linux, the default PortAudio/PortMidi settings will result in
    higher latency than that which can be achieved using ALSA and/or JACK.
    The PortMusic plugins are audio and MIDI servers, which provide an
    interface to the ALSA drivers, in a manner which is in some respects
    similar but fundamentally different from that provided by JACK. For a
    more detailed comparison please refer to:
  </p>
        <p><a class="ulink" href="http://jackaudio.org/faq" target="_top">http://jackaudio.org/faq</a>
  </p>
        <h4><a id="idp76976144"></a>Using ALSA</h4>
        <p>
    The highest level of control and the lowest possible level of latency
    are to be achieved using the ALSA plugins in combination with the <a class="link" href="CommandFlagsCategory.html#IndexCatMinusSched"><em class="citetitle">--sched</em></a>
     flag. Using <a class="link" href="CommandFlagsCategory.html#IndexCatMinusSched"><em class="citetitle">--sched</em></a> requires that Csound be run as the root user, which may be impossible or undesirable in some
    circumstances.
  </p>
        <p>
    The ALSA plugins require the "name" of a "card" and a "device". Unless
    you have named your "cards" in ~/.asoundrc (or /etc/asound.conf), the
    "names" will actually be numbers. In order to obtain a list of the
    possible configurations, use the command line utilities "aplay",
    "arecord" and "amidi". These utilities are included with most Linux
    distros, or can be downloaded and built from source here:
  </p>
        <p>
          <a class="ulink" href="ftp://ftp.alsa-project.org/pub/utils/" target="_top">ftp://ftp.alsa-project.org/pub/utils/</a>
        </p>
        <h4><a id="idp77023792"></a>Audio Output</h4>
        <p>Running the following command:</p>
        <pre class="screen">
          aplay -l</pre>
        <p>will give you a list of the audio playback devices available on your
    system. Typically this list will look something like:
  </p>
        <div class="literallayout">
          <p>[....]<br />
**** List of PLAYBACK Hardware Devices ****<br />
card 0: A5451 [ALI 5451], device 0: ALI 5451 [ALI 5451]<br />
[....]<br />
</p>
        </div>
        <p>If you have more than one card on your system, or if there is more
        than one device on your card, the list will of course be more
        complicated, however in all cases the information that is pertinent is
        the number/name of the card/device. In order to use the above
        soundcard for audio output, the following flag would be added to the
        Csound command line, ~/.csoundrc, or the &lt;CsOptions&gt;section of a
        CSD:
    </p>
        <pre class="screen">
          -+rtaudio=alsa -o dac</pre>
        <h4><a id="idp77028848"></a>Output with dmix</h4>
        <p>
    If you would like to use Csound with dmix and your soundcard does not
    support hardware mixing of audio streams, special care is needed in setting
    up of software (-b) and hardware (-B) buffers.  If you get a message from
    Csound's ALSA driver that looks like the following:
  </p>
        <pre class="screen">
ALSA: -B 8192 not allowed on this device; use 7526 instead</pre>
        <p>
    there is a good chance that you may be using dmix.  If you are using dmix,
    the -b and -B settings of Csound must be synced the period_size and
    buffer_size of dmix respectively, using a ratio of the sr for the Csound
    project to the sample rate that dmix is set up to.  The following formula
    will determine what settings to use for Csound given the settings of dmix:
  </p>
        <pre class="screen">
-b = (csound_sr/dmix_sample_rate) * dmix_period_size
-B = (csound_sr/dmix_sample_rate)  * dmix_buffer_size</pre>
        <p>
    For example, if dmix is set to 48000 sample rate, a period_size of 1024,
    and a buffer_size of 8192, when running a Csound project with sr=48000,
    the settings for buffers should be "-b 1024 -B8192".  If the sr=24000,
    the settings for buffers should be "-b 512 -B4096".
  </p>
        <p>
    Because of this relationship, if a Csound project's sr does not evenly
    divide into the sample_rate used by dmix, then it may be difficult if not
    imposible to set the correct setting for -b and -B due to rounding errors.
    It is suggested then that if you are using sample rates different than
    what your setting is for dmix, then you may want to configure dmix to
    have a period_size and buffer_size that can be evenly divided by the ratio
    between the csound sr and dmix sample_rate.  For example, to run a project
    with sr=16000, the following dmix setting:
  </p>
        <pre class="screen">
pcm.amix {
   type dmix
   ipc_key 50557
   slave {
       pcm "hw:0,0"
       period_time 0
       #period_size 1024
       #buffer_size 8192
       period_size 1536
       buffer_size 12288
   }
   bindings {
       0 0
       1 1
   }
}

# route ALSA software through pcm.amix
pcm.!default {
   type plug
   slave.pcm "amix"
}</pre>
        <p>   with period_size 1536 and buffer_size 12288 will divide nicely by 3 
    (the ratio of the csound sr to the dmix sample_rate) to get "-b 512 -B4096" 
    ( (16000/48000) * 1536 = 512, (16000/48000) * 12288 = 4096 ).

  </p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <table border="0" summary="Note: Note">
            <tr>
              <td rowspan="2" align="center" valign="top" width="25">
                <img alt="[Note]" src="images/note.png" />
              </td>
              <th align="left">Note</th>
            </tr>
            <tr>
              <td align="left" valign="top">
                <p>
      For most soundcards that this affects, the default sample rate for the
      card will be 48000 and the defaults for dmix will be 1024 and 8192.
    </p>
              </td>
            </tr>
          </table>
        </div>
        <h4><a id="idp77036848"></a>Audio Input</h4>
        <p>
      Typically the same card will be used for both input and output, so to
      continue using the foregoing example, the flag:
    </p>
        <pre class="screen">
          -i adc:hw:0,0</pre>
        <p>would be added for audio input from Card 0 Device 0. To use the
      default card employ one of the following flags, with the forementioned
      warning that this will not necessarily work:
    </p>
        <pre class="screen">
          -i adc</pre>
        <p>If you wish to use a different card or device for input, running the
      following utility from the command line will provide a list of input
      devices:
    </p>
        <pre class="screen">
          arecord -l</pre>
        <p>If, by way of an example, you wanted to use a USB audio interface,
      which is the second "card" in your system, for output, but wanted to
      use your internal soundcard, the first card in your setup, for input,
      you would put the following flags somewhere useful:
    </p>
        <pre class="screen">
          -+rtaudio=alsa -i adc:hw:0,0 -o dac:hw:1,0</pre>
        <p>If you wanted to use the second device on your USB interface, to send
      audio to a specific channel, for instance, you would use the following
      flags:
    </p>
        <pre class="screen">
          -+rtaudio=alsa -i adc:hw:0,0 -o dac:hw:1,1</pre>
        <h4><a id="idp77043712"></a>MIDI Input</h4>
        <p>Csound does not automatically create its own ALSA sequencer port. It creates
      an ALSA raw midi port each time it runs. In order to enable your orchestra to receive MIDI input you can use VirMIDI or MIDIThru, whichever you prefer. Setting up these
      virtual MIDI ports is a topic that has been covered extensively
      elsewhere, see 
      <a class="ulink" href="http://www.midi-howto.com/" target="_top">The Linux MIDI how-to</a> 
      or browse your distro's documentation or the ALSA documentation for
      instructions on how to install and configure either VirMIDI or
      MIDIThru (seqdummy). Once you have done so run:
    </p>
        <pre class="screen">
          amidi -l</pre>
        <p>for a list of available devices. Typically this will look something
      like the following:
    </p>
        <div class="literallayout">
          <p>    [....]<br />
Device    Name<br />
hw:1,0    Virtual Raw MIDI (16 subdevices)<br />
hw:1,1    Virtual Raw MIDI (16 subdevices)<br />
hw:1,2    Virtual Raw MIDI (16 subdevices)<br />
hw:1,3    Virtual Raw MIDI (16 subdevices)<br />
hw:2,0,0  PCR MIDI<br />
hw:2,0,1  PCR 1</p>
        </div>
        <p>In this example, Csound can connect to any of the four available
      Virtual Raw MIDI ports, where it will listen for MIDI input. The
      following flag instructs Csound to listen on the first of these ports:
    </p>
        <pre class="screen">
          -+rtmidi=alsa -Mhw:1,0</pre>
        <p>
      You will then need to connect your hardware or software controller to
      the port which is hosting your Csound synthesizer. The simplest way to do
      this is using the "aconnect" utility. Run:
    </p>
        <pre class="screen">
          aconnect -li</pre>
        <p>for a list of available input devices, and:</p>
        <pre class="screen">
          aconnect -lo</pre>
        <p>for a list of available output devices (including the port to which
      Csound has been connected). These should give something like the following:
    </p>
        <div class="literallayout">
          <p><br />
#aconnect -li<br />
client 0: 'System' [type=kernel]<br />
    0 'Timer           '<br />
    1 'Announce        '<br />
        Connecting To: 15:0<br />
client 20: 'Virtual Raw MIDI 1-0' [type=kernel]<br />
    0 'VirMIDI 1-0     '<br />
client 21: 'Virtual Raw MIDI 1-1' [type=kernel]<br />
    0 'VirMIDI 1-1     '<br />
client 22: 'Virtual Raw MIDI 1-2' [type=kernel]<br />
    0 'VirMIDI 1-2     '<br />
client 23: 'Virtual Raw MIDI 1-3' [type=kernel]<br />
    0 'VirMIDI 1-3     '<br />
client 24: 'PCR' [type=kernel]<br />
    0 'PCR MIDI        '<br />
    1 'PCR 1           '<br />
    2 'PCR 2           '</p>
        </div>
        <div class="literallayout">
          <p><br />
#aconnect -lo<br />
client 20: 'Virtual Raw MIDI 1-0' [type=kernel]<br />
    0 'VirMIDI 1-0     '<br />
client 21: 'Virtual Raw MIDI 1-1' [type=kernel]<br />
    0 'VirMIDI 1-1     '<br />
client 22: 'Virtual Raw MIDI 1-2' [type=kernel]<br />
    0 'VirMIDI 1-2     '<br />
client 23: 'Virtual Raw MIDI 1-3' [type=kernel]<br />
    0 'VirMIDI 1-3     '<br />
client 24: 'PCR' [type=kernel]<br />
    0 'PCR MIDI        '<br />
    1 'PCR 1           '</p>
        </div>
        <p>
      In the following example, the USB keyboard which is listed above as
      client 24 will be connected to a Csound synthesizer which is listening
      on the first VirMIDI port. The keyboard has three output ports. The
      first (24:0) transmits messages received on the MIDI in port, the
      second (24:1) transmits keyboard and controller messages, and the
      third (24:2) transmits system exclusive messages. The following
      command connects the second port of the keyboard to the Csound
      synthesizer:</p>
        <pre class="screen">
          aconnect 24:1 20:0</pre>
        <p>Remember that Csound acts as a raw MIDI device and is not an ALSA sequencer client. This means that Csound will not appear in MIDI device listings and will not be available for use directly with <span class="emphasis"><em>aconnect</em></span>, so you must connect to a virtual device (like 'virtual raw MIDI' or 'MIDI through') for persistent connections, or conect directly to the destination using command line flags.</p>
        <h4><a id="idp77058128"></a>MIDI Output</h4>
        <p>Csound can be connected to any device which shows up on the ALSA
      sequencer list of output ports, obtained by "amidi -l" as above. In
      order to connect a Csound synthesizer to the MIDI out port of the
      keyboard listed above, the following flag would be used:</p>
        <pre class="screen">
          -Qhw:2,0,0</pre>
        <h4><a id="idp77059904"></a>Scheduling</h4>
        <p>If you are able to run Csound as the root user, using the "--sched"
      flag will dramatically improve realtime performance, when using ALSA,
      however you may hang your system if you do something stupid. DO NOT
      use "--sched" if you are using JACK for audio output. JACK controls
      scheduling for the audio applications connected to it, and also tries
      to run at the highest possible priority. If the "--sched" flag is
      used, Csound and JACK will be competing rather than cooperating,
      resulting in extremely poor performance. </p>
        <h4><a id="idp77061280"></a>Using JACK</h4>
        <p>The simplest way to use the JACK plugin enabling input and output is as follows:
        </p>
        <pre class="screen">
          -+rtaudio=jack -i adc -o dac</pre>
        <p>
        Additionally, there are some command line options specific to JACK:
        </p>
        <div class="variablelist">
          <p class="title">
            <strong>JACK Command-line Flags</strong>
          </p>
          <dl class="variablelist">
            <dt>
              <span class="term">-+jack_client=[client_name]</span>
            </dt>
            <dd>
              <p>
                The client name used by Csound, defaults to 'csound5'.
                If multiple instances of Csound connect to the JACK server,
                different client names need to be used to avoid name
                conflicts.
              </p>
            </dd>
            <dt>
              <span class="term">-+jack_inportname=[input port name prefix], -+jack_outportname=[output port name prefix]
            </span>
            </dt>
            <dd>
              <p>
                Name prefix of Csound JACK input/output ports; the default is
                'input' and 'output'. The actual port name is the channel number
                appended to the name prefix.
                Example: with the above default settings, a stereo orchestra will
                create these ports in full duplex operation:
                </p>
              <pre class="screen">
csound5:input1              (record left)
csound5:input2              (record right)
csound5:output1             (playback left)
csound5:output2             (playback right)</pre>
              <p>
              </p>
            </dd>
            <dt>
              <span class="term">-+jack_sleep_time=[sleep time in microseconds]</span>
            </dt>
            <dd>
              <p>
                As of Csound version 5.01, this option is deprecated and
                ignored.
              </p>
            </dd>
          </dl>
        </div>
        <p>
      </p>
        <h4><a id="idp77070256"></a>Connecting Csound to other JACK clients</h4>
        <p>
        By default, no connections are made (you need to use jack_connect,
        qjackctl, or a similar utility); however, the plugin can connect to
        ports specified as '-iadc:portname_prefix' or
        '-odac:portname_prefix', where portname_prefix is the full name of
        a port without a channel number, such as 'alsa_pcm:capture_' (for
        -i adc), or 'alsa_pcm:playback_' (for -o dac).
      </p>
        <h4><a id="idp77071504"></a>Notes on buffer sizes</h4>
        <p>
        Audio data is received from and sent to the JACK server by Csound
        using a ring buffer that is controlled by the -b and -B flags.
        -B is the total size of the buffer, while -b is the size of a
        single period. These values are rounded so that the total size is
        an integer multiple of, and greater than the period size.
        The difference of the Csound buffer and period size must be greater
        than or equal to the JACK period size.
      </p>
        <p>
	If both -iadc and -odac are used at the same time, the -b option
	should be set to an integer multiple of ksmps.
      </p>
        <p>
	An example of buffer settings for low latency on a fast system:
	</p>
        <pre class="screen">
          jackd -d alsa -P -r 48000 -p 64 -n 4 -zt &amp;
          csound -+rtaudio=jack -b 64 -B 256 [...]</pre>
        <p>
	with real time scheduling (as root):
	</p>
        <pre class="screen">
          jackd -R -P 90 -d alsa -P -r 48000 -p 64 -n 2 -zt &amp;
          csound --sched=80,90,10 -d -+rtaudio=jack -b 64 -B 192 [...]</pre>
        <p>
	To improve performance, use ksmps values like 32 and 64.
      </p>
        <p>
	The sample rate of the orchestra must be the same as that of the
	JACK server.
      </p>
        <h4><a id="idp77076272"></a>Using Pulseaudio</h4>
        <p>Support for <a class="ulink" href="http://www.pulseaudio.org/" target="_top">Pulseaudio</a> was added in Csound 5.09. You can specify the following settings:</p>
        <div class="orderedlist">
          <ol class="orderedlist" type="1">
            <li class="listitem">Sink names: it's possible to use a number instead of the full name, so
      -odac:1  would select your second device (count starts at 0).</li>
            <li class="listitem">Server name: it's possible to connect to a specific server by using
      -+server=&lt;server_string&gt;
        where server_string is a name of a server or a more
        complex server selection string (see <a class="ulink" href="http://www.pulseaudio.org/" target="_top">pulseaudio.org</a> on
        server strings). This should be network transparent and should allow connections to remote machines.</li>
            <li class="listitem">Stream names: it is possible to label the streams generated by csound, by
            using
            -+output_stream=&lt;stream-name&gt;
              and
              -+input_stream=&lt;stream-name&gt;</li>
          </ol>
        </div>
        <p>Here's an example command line:</p>
        <div class="literallayout">
          <p>csound -odac:1 examples/trapped.csd -+rtaudio=pulse -+server=unix:/tmp/pulse-victor/native -+output_stream=trapped</p>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="UsingDesign.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="Using.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="RealTimeWindows.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">How Csound works </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Windows</td>
        </tr>
      </table>
    </div>
  </body>
</html>
